home *** CD-ROM | disk | FTP | other *** search
/ CU Amiga Super CD-ROM 21 / CU Amiga Magazine's Super CD-ROM 21 (1998)(EMAP Images)(GB)[!][issue 1998-04].iso / CUCD / Programming / AsyncIO / asyncio.doc next >
Text File  |  1997-06-28  |  16KB  |  465 lines
  1. TABLE OF CONTENTS
  2.  
  3. asyncio/CloseAsync
  4. asyncio/FGetsAsync
  5. asyncio/FGetsLenAsync
  6. asyncio/OpenAsync
  7. asyncio/ReadAsync
  8. asyncio/ReadCharAsync
  9. asyncio/ReadLineAsync
  10. asyncio/SeekAsync
  11. asyncio/WriteAsync
  12. asyncio/WriteCharAsync
  13. asyncio/WriteLineAsync
  14. asyncio/CloseAsync                                         asyncio/CloseAsync
  15.  
  16.    NAME
  17.     CloseAsync -- close an async file.
  18.  
  19.    SYNOPSIS
  20.     success = CloseAsync( file );
  21.       d0                   a0
  22.  
  23.     LONG CloseAsync( struct AsyncFile * );
  24.  
  25.    FUNCTION
  26.     Closes a file, flushing any pending writes. Once this call has been
  27.     made, the file can no longer be accessed.
  28.  
  29.    INPUTS
  30.     file - the file to close. May be NULL, in which case this function
  31.            returns -1 and sets the IoErr() code to ERROR_INVALID_LOCk.
  32.  
  33.    RESULT
  34.     result - < 0 for an error, >= 0 for success. Indicates whether closing
  35.         the file worked or not. If the file was opened in read-mode,
  36.         then this call will always work. In case of error,
  37.         dos.library/IoErr() can give more information.
  38.  
  39.    SEE ALSO
  40.     OpenAsync(), dos.library/Close()
  41.  
  42. asyncio/FGetsAsync                                         asyncio/FGetsAsync
  43.  
  44.    NAME
  45.     FGetsAsync -- read a line from an async file, fgets-style.
  46.  
  47.    SYNOPSIS
  48.     buffer = FGetsAsync( file, buffer, size );
  49.       d0                  a0     a1     d0
  50.  
  51.     APTR ReadLineAsync( struct AsyncFile *, APTR, LONG );
  52.  
  53.    FUNCTION
  54.     This function reads a single line from an async file, stopping at
  55.     either a NEWLINE character or EOF. In either event, UP TO the
  56.     number of size specified bytes minus 1 will be copied into the
  57.     buffer. It returns the number of bytes put into the buffer,
  58.     excluding the null-termination. 0 indicates EOF, and -1 indicates
  59.     read error.
  60.  
  61.         If terminated by a newline, the newline WILL be the last character in
  62.         the buffer. The string read in IS null-terminated.
  63.  
  64.    INPUTS
  65.     file - opened file to read from, as obtained from OpenAsync()
  66.     buffer - buffer to read the line into.
  67.     size - size of the buffer, in bytes.
  68.  
  69.    RESULT
  70.     buffer - Pointer to buffer passed in, or NULL for immediate EOF or
  71.         for an error. If NULL is returned for EOF, then
  72.         dos.library/IoErr() returns 0.
  73.  
  74.    SEE ALSO
  75.     OpenAsync(), CloseAsync(), ReadCharAsync(), WriteLineAsync(),
  76.     FGetsLenAsync(), ReadLineAsync(), dos.library/FGets()
  77.  
  78. asyncio/FGetsLenAsync                                   asyncio/FGetsLenAsync
  79.  
  80.    NAME
  81.     FGetsLenAsync -- read a line from an async file.
  82.  
  83.    SYNOPSIS
  84.     buffer = FGetsLenAsync( file, buffer, size, length );
  85.       d0                     a0     a1     d0     a2
  86.  
  87.     APTR FGetsLenAsync( struct AsyncFile *, APTR, LONG, LONG * );
  88.  
  89.    FUNCTION
  90.     This function reads a single line from an async file, stopping at
  91.     either a NEWLINE character or EOF. In either event, UP TO the
  92.     number of size specified bytes minus 1 will be copied into the
  93.     buffer. It returns the number of bytes put into the buffer,
  94.     excluding the null-termination. 0 indicates EOF, and -1 indicates
  95.     read error.
  96.  
  97.     If terminated by a newline, the newline WILL be the last character in
  98.     the buffer. The string read in IS null-terminated.
  99.  
  100.    INPUTS
  101.     file - opened file to read from, as obtained from OpenAsync()
  102.     buffer - buffer to read the line into.
  103.     size - size of the buffer, in bytes.
  104.     length - pointer to ULONG to hold the length of the line, excluding
  105.         the terminating null.
  106.  
  107.    RESULT
  108.     buffer - Pointer to buffer passed in, or NULL for immediate EOF or
  109.         for an error. If NULL is returned for EOF, then
  110.         dos.library/IoErr() returns 0.
  111.  
  112.    SEE ALSO
  113.     OpenAsync(), CloseAsync(), ReadCharAsync(), WriteLineAsync(),
  114.     FGetsAsync(), ReadLineAsync(), dos.library/FGets()
  115.  
  116. asyncio/OpenAsync                                           asyncio/OpenAsync
  117.  
  118.    NAME
  119.     OpenAsync -- open a file for asynchronous IO.
  120.  
  121.    SYNOPSIS
  122.     file = OpenAsync( fileName, accessMode, bufferSize
  123.      d0                  a0         d0          d1
  124.                                            [, sysbase, dosbase ] );
  125.                                                 a1       a2
  126.  
  127.     struct AsyncFile *OpenAsync( const STRPTR, LONG, LONG
  128.                        [, struct ExecBase *, struct DosLibrary * ] );
  129.  
  130.     file = OpenAsyncFromFH( handle, accessMode, bufferSize
  131.                               a0        d0          d1
  132.                                            [, sysbase, dosbase ] );
  133.                                                 a1       a2
  134.  
  135.     struct AsyncFile *OpenAsyncFromFH( BPTR, LONG, LONG
  136.                        [, struct ExecBase *, struct DosLibrary * ] );
  137.  
  138.    FUNCTION
  139.     The named file is opened and an async file handle returned. If the
  140.     accessMode is MODE_READ, an existing file is opened for reading.
  141.     If accessMode is MODE_WRITE, a new file is created for writing. If
  142.     a file of the same name already exists, it is first deleted. If
  143.     accessMode is MODE_APPEND, an existing file is prepared for writing.
  144.     Data written is added to the end of the file. If the file does not
  145.     exists, it is created.
  146.  
  147.     'fileName' is a filename and CANNOT be a window specification such as
  148.     CON: or RAW:, or "*"
  149.  
  150.     'bufferSize' specifies the size of the IO buffer to use. There are
  151.     in fact two buffers allocated, each of roughly (bufferSize/2) bytes
  152.     in size. The actual buffer size use can vary slightly as the size
  153.     is rounded to speed up DMA.
  154.  
  155.     If the file cannot be opened for any reason, the value returned
  156.     will be NULL, and a secondary error code will be available by
  157.     calling the routine dos.library/IoErr().
  158.  
  159.     INPUTS
  160.     name - name of the file to open, cannot be a window specification
  161.     accessMode - one of MODE_READ, MODE_WRITE, or MODE_APPEND
  162.     bufferSize - size of IO buffer to use. 8192 is recommended as it
  163.         provides very good performance for relatively little memory.
  164.     sysbase - Library base needed for the "no externals" version of the
  165.         library.
  166.     dosbase - Library base, as sysbase.
  167.  
  168.     RESULTS
  169.     file - an async file handle or NULL for failure. You should not access
  170.         the fields in the AsyncFile structure, these are private to the
  171.         async IO routines. In case of failure, dos.library/IoErr() can
  172.         give more information.
  173.  
  174.     NOTES (by MH)
  175.     Although stated that CON:, RAW:, or "*" cannot be used as the file
  176.     name, tests indicates that the 2.0+ "Console:" volume is safe to
  177.     use for writing (haven't tested reading). No guarantees though.
  178.  
  179.     Also note that there is no MODE_READWRITE for AsyncIO. You cannot
  180.     read and write to the same AsyncFile.
  181.  
  182.     SEE ALSO
  183.     CloseAsync(), dos.library/Open()
  184.  
  185. asyncio/PeekAsync                                           asyncio/PeekAsync
  186.  
  187.    NAME
  188.     PeekAsync -- read bytes from an async file without advancing file
  189.         pointer.
  190.  
  191.    SYNOPSIS
  192.     actualLength = PeekAsync( file, buffer, numBytes );
  193.          d0                    a0     a1       d0
  194.  
  195.    FUNCTION
  196.     This function tries to read bytes of information from an opened
  197.     async file into the buffer given. 'numBytes' is the number of bytes
  198.     to read from the file.
  199.  
  200.     The read is done without advancing the file pointer, and the read
  201.     is limited to what is available in the current buffer (or the next
  202.     buffer, if the current buffer is empty). If the current buffer does
  203.     not contain 'numBytes' bytes, only the bytes left in the buffer is
  204.     read.
  205.  
  206.     Using PeekAsync() can remove the need to SeekAsync() back after some
  207.     ReadAsync() calls (making your read operations more pipe friendly).
  208.  
  209.     The value returned is the length of the information actually read.
  210.     So, when 'actualLength' is greater than zero, the value of
  211.     'actualLength' is the the number of characters read. A value of
  212.     zero means that end-of-file has been reached. Errors are indicated
  213.     by a value of -1.
  214.  
  215.     INPUTS
  216.     file - opened file to read, as obtained from OpenAsync()
  217.     buffer - buffer where to put bytes read
  218.     numBytes - number of bytes to read into buffer
  219.  
  220.     RESULT
  221.     actualLength - actual number of bytes read, or -1 if an error. In
  222.         case of error, dos.library/IoErr() can give more information.
  223.  
  224.     SEE ALSO
  225.     OpenAsync(), CloseAsync(), ReadCharAsync(), WriteAsync(),
  226.     dos.library/Read()
  227.  
  228.  
  229. asyncio/ReadAsync                                           asyncio/ReadAsync
  230.  
  231.    NAME
  232.     ReadAsync -- read bytes from an async file.
  233.  
  234.    SYNOPSIS
  235.     actualLength = ReadAsync( file, buffer, numBytes );
  236.          d0                    a0     a1       d0
  237.  
  238.     LONG ReadAsync( struct AsyncFile *, APTR, LONG );
  239.  
  240.    FUNCTION
  241.     This function reads bytes of information from an opened async file
  242.     into the buffer given. 'numBytes' is the number of bytes to read from
  243.     the file.
  244.  
  245.     The value returned is the length of the information actually read.
  246.     So, when 'actualLength' is greater than zero, the value of
  247.     'actualLength' is the the number of characters read. Usually
  248.     ReadAsync() will try to fill up your buffer before returning. A value
  249.     of zero means that end-of-file has been reached. Errors are indicated
  250.     by a value of -1.
  251.  
  252.     INPUTS
  253.     file - opened file to read, as obtained from OpenAsync()
  254.     buffer - buffer where to put bytes read
  255.     numBytes - number of bytes to read into buffer
  256.  
  257.     RESULT
  258.     actualLength - actual number of bytes read, or -1 if an error. In
  259.         case of error, dos.library/IoErr() can give more information.
  260.  
  261.     SEE ALSO
  262.     OpenAsync(), CloseAsync(), ReadCharAsync(), WriteAsync(),
  263.     dos.library/Read()
  264.  
  265. asyncio/ReadCharAsync                                   asyncio/ReadCharAsync
  266.  
  267.    NAME
  268.     ReadCharAsync -- read a single byte from an async file.
  269.  
  270.    SYNOPSIS
  271.     byte = ReadCharAsync( file );
  272.      d0                    a0
  273.  
  274.     LONG ReadCharAsync( struct AsyncFile * );
  275.  
  276.    FUNCTION
  277.     This function reads a single byte from an async file. The byte is
  278.     returned, or -1 if there was an error reading, or if the end-of-file
  279.     was reached.
  280.  
  281.    INPUTS
  282.     file - opened file to read from, as obtained from OpenAsync()
  283.  
  284.    RESULT
  285.     byte - the byte read, or -1 if no byte was read. In case of error,
  286.         dos.library/IoErr() can give more information. If IoErr()
  287.         returns 0, it means end-of-file was reached. Any other value
  288.         indicates an error.
  289.  
  290.    SEE ALSO
  291.     OpenAsync(), CloseAsync(), ReadAsync(), WriteCharAsync()
  292.     dos.library/Read()
  293.  
  294. asyncio/ReadLineAsync                                   asyncio/ReadLineAsync
  295.  
  296.    NAME
  297.     ReadLineAsync -- read a line from an async file.
  298.  
  299.    SYNOPSIS
  300.     bytes = ReadLineAsync( file, buffer, size );
  301.      d0                     a0     a1     d0
  302.  
  303.     LONG ReadLineAsync( struct AsyncFile *, APTR, ULONG );
  304.  
  305.    FUNCTION
  306.     This function reads a single line from an async file, stopping at
  307.     either a NEWLINE character or EOF. In either event, UP TO the
  308.     number of size specified bytes minus 1 will be copied into the
  309.     buffer. It returns the number of bytes put into the buffer,
  310.     excluding the null-termination. 0 indicates EOF, and -1 indicates
  311.     read error.
  312.  
  313.     If the line in the file is longer than the buffer, the line will be
  314.     truncated (any newline will be present). Any data left in the file
  315.     upto the newline will be lost.
  316.  
  317.     If terminated by a newline, the newline WILL be the last character in
  318.     the buffer. The string read in IS null-terminated.
  319.  
  320.    INPUTS
  321.     file - opened file to read from, as obtained from OpenAsync()
  322.     buffer - buffer to read the line into.
  323.     size - size of the buffer, in bytes.
  324.  
  325.    RESULT
  326.     bytes - number of bytes read. In case of error (-1 is returned)
  327.         dos.library/IoErr() can give more information. EOF is indicated
  328.         by a return of 0.
  329.  
  330.    SEE ALSO
  331.     OpenAsync(), CloseAsync(), ReadCharAsync(), FGetsAsync(),
  332.     WriteLineAsync(), dos.library/FGets()
  333.  
  334. asyncio/SeekAsync                                           asyncio/SeekAsync
  335.  
  336.    NAME
  337.     SeekAsync -- set the current position for reading or writing within
  338.         an async file.
  339.  
  340.    SYNOPSIS
  341.     oldPosition = SeekAsync( file, position, mode );
  342.          d0                   a0      d0      d1
  343.  
  344.     LONG SeekAsync( struct AsyncFile *, LONG, LONG );
  345.  
  346.    FUNCTION
  347.     SeekAsync() sets the read/write cursor for the file 'file' to the
  348.     position 'position'. This position is used by the various read/write
  349.     functions as the place to start reading or writing. The result is the
  350.     current absolute position in the file, or -1 if an error occurs, in
  351.     which case dos.library/IoErr() can be used to find more information.
  352.     'mode' can be MODE_START, MODE_CURRENT or MODE_END. It is used to
  353.     specify the relative start position. For example, 20 from current
  354.     is a position 20 bytes forward from current, -20 is 20 bytes back
  355.     from current.
  356.  
  357.     To find out what the current position within a file is, simply seek
  358.     zero from current.
  359.  
  360.     INPUTS
  361.     file - an opened async file, as obtained from OpenAsync()
  362.     position - the place where to move the read/write cursor
  363.     mode - the mode for the position, one of MODE_START, MODE_CURRENT,
  364.         or MODE_END.
  365.  
  366.     RESULT
  367.     oldPosition - the previous position of the read/write cursor, or -1
  368.         if an error occurs. In case of error, dos.library/IoErr() can
  369.         give more information.
  370.  
  371.     NOTES (by MH)
  372.     If you seek after having read only a few bytes, the function must
  373.     wait for both buffers to be loaded, before the seek can be done.
  374.     This can cause small delays. Note that the above case isn't the
  375.     only one, but the typical one.
  376.  
  377.     SEE ALSO
  378.     OpenAsync(), CloseAsync(), ReadAsync(), WriteAsync(),
  379.     dos.library/Seek()
  380.  
  381. asyncio/WriteAsync                                         asyncio/WriteAsync
  382.  
  383.    NAME
  384.     WriteAsync -- write data to an async file.
  385.  
  386.    SYNOPSIS
  387.     actualLength = WriteAsync( file, buffer, numBytes );
  388.          d0                     a0     a1       d0
  389.  
  390.     LONG WriteAsync( struct AsyncFile *, APTR, LONG );
  391.  
  392.    FUNCTION
  393.     WriteAsync() writes bytes of data to an opened async file. 'numBytes'
  394.     indicates the number of bytes of data to be transferred. 'buffer'
  395.     points to the data to write. The value returned is the length of
  396.     information actually written. So, when 'actualLength' is greater
  397.     than zero, the value of 'actualLength' is the number of characters
  398.     written. Errors are indicated by a return value of -1.
  399.  
  400.     INPUTS
  401.     file - an opened file, as obtained from OpenAsync()
  402.     buffer - address of data to write
  403.     numBytes - number of bytes to write to the file
  404.  
  405.     RESULT
  406.     actualLength - number of bytes written, or -1 if error. In case
  407.         of error, dos.library/IoErr() can give more information.
  408.  
  409.     SEE ALSO
  410.     OpenAsync(), CloseAsync(), ReadAsync(), WriteCharAsync(),
  411.     dos.library/Write()
  412.  
  413. asyncio/WriteCharAsync                                 asyncio/WriteCharAsync
  414.  
  415.    NAME
  416.     WriteCharAsync -- write a single byte to an async file.
  417.  
  418.    SYNOPSIS
  419.     result = WriteCharAsync( file, byte );
  420.       d0                      a0    d0
  421.  
  422.     LONG WriteCharAsync( struct AsyncFile *, UBYTE );
  423.  
  424.    FUNCTION
  425.     This function writes a single byte to an async file.
  426.  
  427.    INPUTS
  428.     file - an opened async file, as obtained from OpenAsync()
  429.     byte - byte of data to add to the file
  430.  
  431.    RESULT
  432.     result - 1 if the byte was written, -1 if there was an error. In
  433.         case of error, dos.library/IoErr() can give more information.
  434.  
  435.    SEE ALSO
  436.     OpenAsync(), CloseAsync(), ReadAsync(), WriteAsync(),
  437.     dos.library/Write()
  438.  
  439. asyncio/WriteLineAsync                                 asyncio/WriteLineAsync
  440.  
  441.    NAME
  442.     WriteLineAsync -- write a line to an async file.
  443.  
  444.    SYNOPSIS
  445.     bytes = WriteLineAsync( file, buffer );
  446.  
  447.     LONG WriteLineAsync( struct AsyncFile *, STRPTR );
  448.  
  449.    FUNCTION
  450.     This function writes an unformatted string to an async file. No
  451.     newline is appended to the string.
  452.  
  453.    INPUTS
  454.     file - opened file to read from, as obtained from OpenAsync()
  455.     buffer - buffer to write to the file
  456.  
  457.    RESULT
  458.     bytes - number of bytes written, or -1 if there was an error. In
  459.         case of error, dos.library/IoErr() can give more information.
  460.  
  461.    SEE ALSO
  462.     OpenAsync(), CloseAsync(), ReadCharAsync(), WriteCharAsync(),
  463.     FGetsAsync(), FGetsLenAsync(), ReadLineAsync(), dos.library/FPuts()
  464.  
  465.